{
 "cells": [
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    ".. _categorical_tutorial:\n",
    "\n",
    ".. currentmodule:: seaborn"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "Plotting with categorical data\n",
    "==============================\n",
    "\n",
    ".. raw:: html\n",
    "\n",
    "   <div class=col-md-9>\n",
    "   \n",
    "In the :ref:`relational plot tutorial <relational_tutorial>` we saw how to use different visual representations to show the relationship between multiple variables in a dataset. In the examples, we focused on cases where the main relationship was between two numerical variables. If one of the main variables is \"categorical\" (divided into discrete groups) it may be helpful to use a more specialized approach to visualization.\n",
    "\n",
    "In seaborn, there are several different ways to visualize a relationship involving categorical data. Similar to the relationship between :func:`relplot` and either :func:`scatterplot` or :func:`lineplot`, there are two ways to make these plots. There are a number of axes-level functions for plotting categorical data in different ways and a figure-level interface, :func:`catplot`, that gives unified higher-level access to them.\n",
    "\n",
    "It's helpful to think of the different categorical plot kinds as belonging to three different families, which we'll discuss in detail below. They are:\n",
    "\n",
    "Categorical scatterplots:\n",
    "\n",
    "- :func:`stripplot` (with ``kind=\"strip\"``; the default)\n",
    "- :func:`swarmplot` (with ``kind=\"swarm\"``)\n",
    "\n",
    "Categorical distribution plots:\n",
    "\n",
    "- :func:`boxplot` (with ``kind=\"box\"``)\n",
    "- :func:`violinplot` (with ``kind=\"violin\"``)\n",
    "- :func:`boxenplot` (with ``kind=\"boxen\"``)\n",
    "\n",
    "Categorical estimate plots:\n",
    "\n",
    "- :func:`pointplot` (with ``kind=\"point\"``)\n",
    "- :func:`barplot` (with ``kind=\"bar\"``)\n",
    "- :func:`countplot` (with ``kind=\"count\"``)\n",
    "\n",
    "These families represent the data using different levels of granularity. When deciding which to use, you'll have to think about the question that you want to answer. The unified API makes it easy to switch between different kinds and see your data from several perspectives.\n",
    "\n",
    "In this tutorial, we'll mostly focus on the figure-level interface, :func:`catplot`. Remember that this function is a higher-level interface each of the functions above, so we'll reference them when we show each kind of plot, keeping the more verbose kind-specific API documentation at hand."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import seaborn as sns\n",
    "import matplotlib.pyplot as plt\n",
    "sns.set(style=\"ticks\", color_codes=True)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": [
     "hide"
    ]
   },
   "outputs": [],
   "source": [
    "%matplotlib inline\n",
    "import numpy as np\n",
    "np.random.seed(sum(map(ord, \"categorical\")))"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "Categorical scatterplots\n",
    "------------------------\n",
    "\n",
    "The default representation of the data in :func:`catplot` uses a scatterplot. There are actually two different categorical scatter plots in seaborn. They take different approaches to resolving the main challenge in representing categorical data with a scatter plot, which is that all of the points belonging to one category would fall on the same position along the axis corresponding to the categorical variable. The approach used by :func:`stripplot`, which is the default \"kind\" in :func:`catplot` is to adjust the positions of points on the categorical axis with a small amount of random \"jitter\":"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "tips = sns.load_dataset(\"tips\")\n",
    "sns.catplot(x=\"day\", y=\"total_bill\", data=tips);"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "The ``jitter`` parameter controls the magnitude of jitter or disables it altogether:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sns.catplot(x=\"day\", y=\"total_bill\", jitter=False, data=tips);"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "The second approach adjusts the points along the categorical axis using an algorithm that prevents them from overlapping. It can give a better representation of the distribution of observations, although it only works well for relatively small datasets. This kind of plot is sometimes called a \"beeswarm\" and is drawn in seaborn by :func:`swarmplot`, which is activated by setting ``kind=\"swarm\"`` in :func:`catplot`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sns.catplot(x=\"day\", y=\"total_bill\", kind=\"swarm\", data=tips);"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "Similar to the relational plots, it's possible to add another dimension to a categorical plot by using a ``hue`` semantic. (The categorical plots do not currently support ``size`` or ``style`` semantics). Each different categorical plotting function handles the ``hue`` semantic differently. For the scatter plots, it is only necessary to change the color of the points:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sns.catplot(x=\"day\", y=\"total_bill\", hue=\"sex\", kind=\"swarm\", data=tips);"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "Unlike with numerical data, it is not always obvious how to order the levels of the categorical variable along its axis. In general, the seaborn categorical plotting functions try to infer the order of categories from the data. If your data have a pandas ``Categorical`` datatype, then the default order of the categories can be set there. If the variable passed to the categorical axis looks numerical, the levels will be sorted. But the data are still treated as categorical and drawn at ordinal positions on the categorical axes (specifically, at 0, 1, ...) even when numbers are used to label them:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sns.catplot(x=\"size\", y=\"total_bill\", kind=\"swarm\",\n",
    "            data=tips.query(\"size != 3\"));"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "The other option for choosing a default ordering is to take the levels of the category as they appear in the dataset. The ordering can also be controlled on a plot-specific basis using the ``order`` parameter. This can be important when drawing multiple categorical plots in the same figure, which we'll see more of below:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sns.catplot(x=\"smoker\", y=\"tip\", order=[\"No\", \"Yes\"], data=tips);"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "We've referred to the idea of \"categorical axis\". In these examples, that's always corresponded to the horizontal axis. But it's often helpful to put the categorical variable on the vertical axis (particularly when the category names are relatively long or there are many categories). To do this, swap the assignment of variables to axes:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sns.catplot(x=\"total_bill\", y=\"day\", hue=\"time\", kind=\"swarm\", data=tips);"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "Distributions of observations within categories\n",
    "-----------------------------------------------\n",
    "\n",
    "As the size of the dataset grows, categorical scatter plots become limited in the information they can provide about the distribution of values within each category. When this happens, there are several approaches for summarizing the distributional information in ways that facilitate easy comparisons across the category levels.\n",
    "\n",
    "Boxplots\n",
    "^^^^^^^^\n",
    "\n",
    "The first is the familiar :func:`boxplot`. This kind of plot shows the three quartile values of the distribution along with extreme values. The \"whiskers\" extend to points that lie within 1.5 IQRs of the lower and upper quartile, and then observations that fall outside this range are displayed independently. This means that each value in the boxplot corresponds to an actual observation in the data."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sns.catplot(x=\"day\", y=\"total_bill\", kind=\"box\", data=tips);"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "When adding a ``hue`` semantic, the box for each level of the semantic variable is moved along the categorical axis so they don't overlap:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sns.catplot(x=\"day\", y=\"total_bill\", hue=\"smoker\", kind=\"box\", data=tips);"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "This behavior is called \"dodging\" and is turned on by default because it is assumed that the semantic variable is nested within the main categorical variable. If that's not the case, you can disable the dodging:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "tips[\"weekend\"] = tips[\"day\"].isin([\"Sat\", \"Sun\"])\n",
    "sns.catplot(x=\"day\", y=\"total_bill\", hue=\"weekend\",\n",
    "            kind=\"box\", dodge=False, data=tips);"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "A related function, :func:`boxenplot`, draws a plot that is similar to a box plot but optimized for showing more information about the shape of the distribution. It is best suited for larger datasets:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "diamonds = sns.load_dataset(\"diamonds\")\n",
    "sns.catplot(x=\"color\", y=\"price\", kind=\"boxen\",\n",
    "            data=diamonds.sort_values(\"color\"));"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "Violinplots\n",
    "^^^^^^^^^^^\n",
    "\n",
    "A different approach is a :func:`violinplot`, which combines a boxplot with the kernel density estimation procedure described in the :ref:`distributions <distribution_tutorial>` tutorial:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sns.catplot(x=\"total_bill\", y=\"day\", hue=\"sex\",\n",
    "            kind=\"violin\", data=tips);"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "This approach uses the kernel density estimate to provide a richer description of the distribution of values. Additionally, the quartile and whisker values from the boxplot are shown inside the violin. The downside is that, because the violinplot uses a KDE, there are some other parameters that may need tweaking, adding some complexity relative to the straightforward boxplot:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sns.catplot(x=\"total_bill\", y=\"day\", hue=\"sex\",\n",
    "            kind=\"violin\", bw=.15, cut=0,\n",
    "            data=tips);"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "It's also possible to \"split\" the violins when the hue parameter has only two levels, which can allow for a more efficient use of space:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sns.catplot(x=\"day\", y=\"total_bill\", hue=\"sex\",\n",
    "            kind=\"violin\", split=True, data=tips);"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "Finally, there are several options for the plot that is drawn on the interior of the violins, including ways to show each individual observation instead of the summary boxplot values:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sns.catplot(x=\"day\", y=\"total_bill\", hue=\"sex\",\n",
    "            kind=\"violin\", inner=\"stick\", split=True,\n",
    "            palette=\"pastel\", data=tips);"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "It can also be useful to combine :func:`swarmplot` or :func:`striplot` with a box plot or violin plot to show each observation along with a summary of the distribution:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "g = sns.catplot(x=\"day\", y=\"total_bill\", kind=\"violin\", inner=None, data=tips)\n",
    "sns.swarmplot(x=\"day\", y=\"total_bill\", color=\"k\", size=3, data=tips, ax=g.ax);"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "Statistical estimation within categories\n",
    "----------------------------------------\n",
    "\n",
    "For other applications, rather than showing the distribution within each category, you might want to show an estimate of the central tendency of the values. Seaborn has two main ways to show this information. Importantly, the basic API for these functions is identical to that for the ones discussed above.\n",
    "\n",
    "Bar plots\n",
    "^^^^^^^^^\n",
    "\n",
    "A familiar style of plot that accomplishes this goal is a bar plot. In seaborn, the :func:`barplot` function operates on a full dataset and applies a function to obtain the estimate (taking the mean by default). When there are multiple observations in each category, it also uses bootstrapping to compute a confidence interval around the estimate, which is plotted using error bars:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "titanic = sns.load_dataset(\"titanic\")\n",
    "sns.catplot(x=\"sex\", y=\"survived\", hue=\"class\", kind=\"bar\", data=titanic);"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "A special case for the bar plot is when you want to show the number of observations in each category rather than computing a statistic for a second variable. This is similar to a histogram over a categorical, rather than quantitative, variable. In seaborn, it's easy to do so with the :func:`countplot` function:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sns.catplot(x=\"deck\", kind=\"count\", palette=\"ch:.25\", data=titanic);"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "Both :func:`barplot` and :func:`countplot` can be invoked with all of the options discussed above, along with others that are demonstrated in the detailed documentation for each function:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sns.catplot(y=\"deck\", hue=\"class\", kind=\"count\",\n",
    "            palette=\"pastel\", edgecolor=\".6\",\n",
    "            data=titanic);"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "Point plots\n",
    "^^^^^^^^^^^\n",
    "\n",
    "An alternative style for visualizing the same information is offered by the :func:`pointplot` function. This function also encodes the value of the estimate with height on the other axis, but rather than showing a full bar, it plots the point estimate and confidence interval. Additionally, :func:`pointplot` connects points from the same ``hue`` category. This makes it easy to see how the main relationship is changing as a function of the hue semantic, because your eyes are quite good at picking up on differences of slopes:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sns.catplot(x=\"sex\", y=\"survived\", hue=\"class\", kind=\"point\", data=titanic);"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "While the categorical functions lack the ``style`` semantic of the relational functions, it can still be a good idea to vary the marker and/or linestyle along with the hue to make figures that are maximally accessible and reproduce well in black and white:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sns.catplot(x=\"class\", y=\"survived\", hue=\"sex\",\n",
    "            palette={\"male\": \"g\", \"female\": \"m\"},\n",
    "            markers=[\"^\", \"o\"], linestyles=[\"-\", \"--\"],\n",
    "            kind=\"point\", data=titanic);"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "Plotting \"wide-form\" data\n",
    "-------------------------\n",
    "\n",
    "While using \"long-form\" or \"tidy\" data is preferred, these functions can also by applied to \"wide-form\" data in a variety of formats, including pandas DataFrames or two-dimensional numpy arrays. These objects should be passed directly to the ``data`` parameter:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "iris = sns.load_dataset(\"iris\")\n",
    "sns.catplot(data=iris, orient=\"h\", kind=\"box\");"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "Additionally, the axes-level functions accept vectors of Pandas or numpy objects rather than variables in a ``DataFrame``:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sns.violinplot(x=iris.species, y=iris.sepal_length);"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "To control the size and shape of plots made by the functions discussed above, you must set up the figure yourself using matplotlib commands:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "f, ax = plt.subplots(figsize=(7, 3))\n",
    "sns.countplot(y=\"deck\", data=titanic, color=\"c\");"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "This is the approach you should take when you need a categorical figure to happily coexist in a more complex figure with other kinds of plots.\n",
    "\n",
    "Showing multiple relationships with facets\n",
    "------------------------------------------\n",
    "\n",
    "Just like :func:`relplot`, the fact that :func:`catplot` is built on a :class:`FacetGrid` means that it is easy to add faceting variables to visualize higher-dimensional relationships:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sns.catplot(x=\"day\", y=\"total_bill\", hue=\"smoker\",\n",
    "            col=\"time\", aspect=.6,\n",
    "            kind=\"swarm\", data=tips);"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "For further customization of the plot, you can use the methods on the :class:`FacetGrid` object that it returns:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "g = sns.catplot(x=\"fare\", y=\"survived\", row=\"class\",\n",
    "                kind=\"box\", orient=\"h\", height=1.5, aspect=4,\n",
    "                data=titanic.query(\"fare > 0\"))\n",
    "g.set(xscale=\"log\");"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    ".. raw:: html\n",
    "\n",
    "    </div>"
   ]
  }
 ],
 "metadata": {
  "celltoolbar": "Tags",
  "kernelspec": {
   "display_name": "Python 3.6  (seaborn-py37-latest)",
   "language": "python",
   "name": "seaborn-py37-latest"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.4"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 1
}
